TFS uses security standards like OAuth 2.0 to authenticate users, and our documentation is public via OpenID Connect standards. To improve API security, we perform API penetration tests regularly and use proven industry standards like REST for our APIs.

What is Oauth 2.0?

OAuth 2 is an authorization framework that enables applications to obtain limited access to APIs on an HTTP(s) service. OAuth 2 provides authorization flows for web and desktop applications, and mobile devices.

Before you can call any of our TFS APIs, you must follow the appropriate OAuth-based authorization procedure to obtain an access token; you then provide that access token with every call.

Client Credentials Grant Type

An access token can be generated by passing your client credentials (Client Id and Client Secret) in the query parameter to a token url (/oauth/token). The operation returns a token that’s good for about 1 hours; when it expires, you just repeat the call and get a new token with a refresh token that was provided from the first API call.

Sample Request Token

A sample request token generated will look like this:

{"access\_token":"6JRti0R02L_79bDdixIPXhCJE5Ye8TrroWI3lufWUYariVFt",

"refresh\_token":"sGLeOMQ3HNyyYql3am4DM_0bi_v0sYJmR4tHMG1C6kly1MUm",

"token\_type":"Bearer",

"expires\_in":3600}

Header

Please use the header below when calling the TFS APIs

Content-Type:

Indicates the content type of the response; value will always be:

application/x-www-form-urlencoded

API Response

When calling TFS APIs, you will receive a "200" response code back if your token and request is valid. However, below are some of the response codes you will receive for various types of reasons:

HTTP Status Codes

302

This status code is returned under two different conditions: one, if the authorization code is successfully returned; and two, if the request includes an invalid scope value or if the end user declines to authorize access (or revokes access after it was initially given).

The authorization code or error information is appended to the provided Redirect URI as one or more query parameters.

400

Returned when there’s an error in the request: the Redirect URI does not match the value defined for the app; the scope value is missing; an unsupported query parameter is included; or any invalid character is used.

401

The client data provided in the request failed validation.

429

The request has been rejected because of rate limiting -- you've sent too many requests in a given amount of time.

500

The API encountered an error while attempting to communicate with the back end.

502

Internal connection failure.

503

Backend at capacity error.

504

Gateway Timeout.